Documentation Mailing Lists FAQ Frequently Asked Questions v2

Answers for: Developer

If you want to translate the ActionApps to another language, you can look at:

• newer versions: look in include/lang/ [add more details]
  Older versions:
• include/en_common_lang.php3
  
  - this is the file with language constants definions which is common to all slices in the AA instalation (e.g cz_common_lang.php3 is the same file for the Czech language)
  
  
• include/en_news_lang.php3
  
  - this is the file with language constants definions for specific slices. It is possible to have slices in different languages. You can choose the language used on the "Admin" -> "Main settings - Slice" page. Hence if you want to have slices in French, you have to copy en_news_lang.php3 to a new file (fr_news_lang.php3 for example) and translate the texts to French to fit your needs.
  
  
• texts in template slice News (EN) template (see Templates section)
  
  
• texts in fields templateslice Action Aplication Core (see Templates section)

Why are slice IDs and item IDs so long?
Would it be possible to make them shorter?

The 32-digits hexadecimal IDs are quite standard in MySQL/PHP - see uniqid() and md5() functions. These identifiers are intended to be unique worldwide so that each item has an unique ID regardless of where it is stored, such as on Econnect's server or on Colnodo's. This feature helps us in cross-server feeding.

Internally (within the database) the IDs are stored as 16-character strings (for disk-space savings and a little better performance of the database), but this is only important for developers.

Because of long URLs, I made short_id in v1.8 - so that the auto-incremented short IDs are used by default. The URL for an item is now, for example:

http://kalendar.ecn.cz/index.shtml?AA_SL_Session=44ca275c691 842965745f90ab9aee24e&x=27968

or, even better:

http://kalendar.ecn.cz/index.shtml?x=27968

Next suggested steps for the upgrading the FAQ:

1. Fix old links within fulltext.
2. Categorize and fix grammer in all articles
3. Get popular collections view working (uses related items) and ask key users to submit their favorite collections.
4. Add more content from email archives and personal notes.
5. Add email alert feature
6. Allow for editing on site for logged in users.

Also need to get other language views and content going (e.g. Spanish).

I also plan to create a Requested Feautre slice in the near future that will use the same alert login.

Some help with updating FAQ content would be most appreciated. :^)

 - JD- - - --

SELECT * FROM item, content
  WHERE item.id = content.item_id                // to join the tables
      AND item.id = 'hey67s[o0-78z._d'           // 16 characters long packed id
                                                 // see util.php3 - q_pack_id()
      AND content.field_id = 'headline........';

This SQL query select all fields from item table (where are stored just the most common item fields - id, short_id, slice_id, status_code, post_date, publish_date, expiry_date, highlight, posted_by, edited_by, last_edit, display_count, flags, disc_count, disc_app, externally_fed) plus the content of 'headline........' field from content table (will be in content.text field). You can change 'headline........' to any field id, of course, just like 'category.......1' or 'source.........1'. Also you can use short_ids as well to identify the item.

Database structure used for items

Data for an item is not stored in one table, as it is obvious and as you probably expect. Data are divided to two tables - item and content. Item table stores the common fields, which is requiered for each item. All other columns are sored in related table content (relation 1:N). The content table is quite easy - item_id, field_id, number, text, flag. Each row holds contents (in 'text' or 'number' filed) of one field (identified by field_id - like 'headline........') for one item (identified by 'item_id' - related to id in 'item' table).

Such, say 'virtual table database structure' or 'object oriented database' allows to store items of any number of fields. It also allows to store multiple values for one field (you just add a row with the same item_id and field_id).

More complicated SQL query, which contain more fields from content table could look like:

SELECT item.*, c1.text, c2.text FROM item, content as c1, content as c2
  WHERE item.id = c1.item_id       // to join the tables
      AND item.id = c2.item_id       // to join the tables
      AND item.short_id = '13432' // we can use short id
      AND c1.field_id = 'headline........';
      AND c2.field_id = 'full_text.......';

To select all extended fields for the item use:

SELECT * FROM content WHERE item_id = 'hey67s[o0-78z._d';

Item data manipulationg functions (data API)

It is important to know how the data are stored in database, but if you want to write some feature to AA, it is strongly recomended not to use direct database access, but rather use three main data API function to access data (especially for storing data into AA database). The functions are independent on database structure behind and it takes care about feeding, clearing the cache and other stuff.

Main AA data API functions are:

function QueryIDs($fields, $slice_id, $conds, $sort="", $group_by="",
                  $type="ACTIVE", $slices="", $neverAllItems=0,
                  $restrict_ids=array() )
  - stored in include/searchlib.php3

function GetItemContent($ids, $use_short_ids=false)
  - stored in include/util.php3

function StoreItem( $id, $slice_id, $content4id, $fields, $insert,
                             $invalidatecache=true, $feed=true )
  - stored in include/itemfunc.php3

By QueryIDs function you will get array of IDs of items based on your conditions, possiblly sorted. Input conditions are stored in array which you already know from design of searchform (conds[0][publish_date....]=...). This function allows you to get IDs based on any number of conditions. Also it is completely database independent, so you need not to know, which field is stored in item table and which is stored in content table.

The content of an item you will get by GetItemContent function. As input parameter use the IDs of the items you want to get (possibly obtained by QueryIDs). The items are then returned in array structure, which is good to know about, because all data manipulation functions in AA uses this structure to access the item data. This structure is also used as parameter to StoreItem function.

Item data structure

Abstract Data Structure for data manipulation in AA (returned by GetItemContent function):

$content[<unpacked_item_id>][<field_id>)][<alternative>][value|flag]

<unpacked_item_id>

is 32 characters long hexadecimal id of item (structure holds data for more than one item, generaly)

<field_id>

is field id as you know it from Admin -> Fields page of AA admin interface ( like 'headline........', 'url............2', ...)

<alternative>

is number used for storing multiple values for the same field. Obviously there is only '0' index, but for field, where we store multiple categories (for example) it will utilize indexes '0', '1' ,... up to number of selected categories for the item

<value

is probably what you care about - it is content of the field like 'An article title' or 1092928827 or <fulltext of item>

flag>

special flags for the content - if the content is HTML formatted, ... The list of possible flags follows (defined in include/constants.php3)

            define( "FLAG_HTML", 1 );      # content is in HTML
            define( "FLAG_FEED", 2 );      # item is fed
            define( "FLAG_FREEZE", 4 );    # content can't be changed
            define( "FLAG_OFFLINE", 8 );   # off-line filled
            define( "FLAG_UPDATE", 16 );   # content should be updated
                                                     # if source is changed
                                                     #   (after feeding)
      

So, to access content of 'headline.........' field for item number 5e72be7289a0be63820a8723837ce21a you can type:

$text = $content['5e72be7289a0be63820a8723837ce21a']['headline........'][0]['value'];

Error returns in AA are not consistent, there is a general, low priority, task to clean up the code as we work on it.

In general use the $err array to return errors.

Some specific examples follow, please add others here.

Each of the functions: insert_fnc_xxx sets for example

$err[image.....1] => "Wrong type of file"

If you find no alias function is good enough for you, you can write your own. function. The alias functions are stored in include/item.php3 file and its names begins with f_ (but we can name it as g_* or such, as well) and they are three letters long (just like f_a()).

All you have to do for new function is:

1. Write your own function in item.php3 (say f_9()).
   
2. Add description of the function into param wizard definition file include/constants_param_wizard.php3 (structure described inside this file)
   
3. Add human readable messages into include/en_param_wizard_lang.php3 language file.
   
   
4. Edit the FAQ item on Alias function paramaters

If you find, that the new alias function is very proprietary (it is unusable for other people, you can create file /include/usr_aliasfnc.php3, which is automaticaly included to code (if exists). There you can define your own alias functions. The function name must be prefixed by 'usr_' prefix. The function have three parameters:

• $columns - array of content of each field in item (for example
  $columns[headline........][0][value] = "This is item title"
  
  • value last array dimension - select between value and flag. Value is field content flag could be FLAG_HTML | FLAG_FEED | FLAG_FREEZE | FLAG_OFFLINE | FLAG_UPDATE
  • 0 - used for multivalue fields (as categories in some slices). For single values we use just 0, for multivalues we use 0, 1, ...
  • headline........ - field id
    
• $col - field id of column for which the alias is definned
  
  
• $param - parameter passed to function from textfied in alias definition (just like usr_cz_date:1). The name of function is in param too!!!

<?php //usr_aliasfnc.php3  

    /** Prints czech date (for Ekolist pages) 
     *  @param columns - array of all field values for all ifelds in current item
     *  @param col     - fileld id of field, for which the alias is defined
     *  @param param   - possibly parameters to alias function passed in alias definition parameter (usr_cz_date:parameter) 
     */
    function usr_cz_date($columns, $col, $param="") { 
        $dte     = $columns[$col][0][value];
        $month   = array( 1 => "ledna", "unora", "brezna", "dubna", "kvetna", "cervna", "cervence", "srpna", "zari", "rijna", "listopadu", "prosince");
        $weekday = array("nedele","pondeli","utery","streda","ctvrtek","patek","sobota");
        $m       = $month[ date("n", $dte)];
        $end     = ( !$param ? "" :  " (". $weekday[ date("w", $dte) ]. ")");
        return date("j", $dte) .". $m ". date("Y", $dte). $end; 
    }
?> 

Such alias function can be called by defining new alias for some field. Just define alias name (as obvious), alias function should be "f_u - user function" and the parameter should be the name of the function ("usr_cz_date" in our example). It is possible to pass parameters to the function. The parameters are separated by colon (usr_cz_date:parameters).

The applications in v1.5+ can be created quite easy.

1. Choose a slice and create the set of fields you want to have in the new application.
   
   
2. For these fields change the default values, help texts, names, priorities, aliases, etc. in the admin interface ("Admin" -> "Main settings - Fields").
   
   
3. Change the design of the fulltext view, list item view and possibly the admin view ("Admin" -> "Design - Fulltext", "Admin" -> "Design - Index", "Admin" -> "Design - Item Manager")
   
   
4. Test the new slice, whether it is working O.K.
   
   
5. Add a new slice based on this one (not a template, but a slice)
   
   
6. Mark the new slice as a Template ("Admin" -> "Main settings - Slice") - to do this you must be the superadministrator (four stars).
   
   

To edit a file, you should work on a copy of the full APC-AA distribution, make changes and then check back the changed files

To check out the whole of apc-aa into some directory or other, you need to do it differently from the standard installation instructions if you plan on editing files.

The first time you use a particular CVS host you need to do ....

$ ssh yourusername@cvs.apc-aa.sourceforge.net

It should log you in, and straight out again (accept the host key if it asks you to)

$ export CVS_RSH=ssh #for bash for example
or
setenv CVS_RSH ssh # for tcsh for example
$ cvs -z3 -d:ext:yourusername@cvs.apc-aa.sourceforge.net:/cvsroot/apc-aa co apc-aa
yourusername@cvs.apc-aa.sourceforge.net's password:

If it doesn't ask for a password, but you get an error about connection refused its probably because it didn't see the CVS_RSH environment variable.

Edit the file, then

If the file is not already in the CVS repository, for example, because you have created a new file, then first add it to CVS with

$ cvs add myfile.htm

then upload with for example

$ cvs commit myfile.htm

Make sure to put in a useful comment when prompted by CVS.

Note, Its best NOT to do a plain

$ cvs commit

As this will commit files that you probably don't want to, especially config.php3

If you get the error:

Could not chdir to home directory /home/users/y/yo/yourusername: No such file or directory
cvs [server aborted]: can't chdir(/home/users/y/yo/yourusernameNo such file or directory

Then you need the ssh trick.

You can't use pserver: to check the files out, if you are going to commit them back again.

(main) developer 2.1.0
stable 2.0.1

Production systems will probably want to work with 2.0.1, although 2.1.0 is fairly stable.

In theory, to discover which version you are using, look in "CHANGES", for example apc-aa.sourceforge.net/aa/CHANGES shows that Sourceforge is still running the stable branch, but note that CHANGES is frequently NOT updated to show the version number of the developer version, and the current developer version shows the same version 2.0.1 with just a few more dated changes.

If you check out the default method:

cvs -z3 -d:ext:yourusername@cvs.apc-aa.sourceforge.net:/cvsroot/apc-aa -r2_0_1 co apc-aa
OR
cvs -d:pserver:anonymous@cvs.apc-aa.sourceforge.net:/cvsroot/apc-aa co -rv2_0_1 apc-aa

you will get the developer branch, but

cvs -z3 -d:ext:yourusername@cvs.apc-aa.sourceforge.net:/cvsroot/apc-aa co apc-aa
OR
cvs -d:pserver:anonymous@cvs.apc-aa.sourceforge.net:/cvsroot/apc-aa co apc-aa

Note that you cannot assume that different branches will run with the same Database.

In particular to upgrade from 2.0.1 to 2.1.0 you need to run sql_update.php3 to upgrade the database fields.

(c) Jakub Adámek, Econnect, January 2003

Since January 17 2003 AA is using the mini-gettext language environment. The language files are in the directory include/lang/.

Each file is connected with one language and a series of PHP scripts. At run-time, you can only use one file for translations at a time, but you can change freely between files by using the bind_mgettext_domain() function in include/mgettext.php3.

The files are maintained by people — translators and by the PHP function xmgettext() in misc/mgettext/xmgettext.php3. Translators add new translations and xmgettext() adds new strings to be translated which it finds in the source files.

Notes for Translators

To add new translations, you only need to find empty strings "" in your language files, e.g. $_m["not yet translated"] = "". Please mind some following notes.

The language files are regular PHP files, you must not break the syntax. You must not change the ID string in _m["..."]. Even if it contains bad English, it may be changed only in the source code, not in the language file. There is also an English translations file, thus small changes may take place there.

You must follow the PHP syntax for strings, using \" and \$ instead of " and $. You must quote the translation with "". (You might quote it with single quotes as well, but next time xmgettext() will be run, it will reformat all strings to double quotes.)

Each language string is preceded by links to source code where it is used. If you are not sure how to translate a string, go to the source code and have a look. Some language strings contain parameters %1,%2 etc. which will be replaced by some variable content at run-time. Place the parameters appropriately in the translation.

The file begins with a list of "Unused messages" which are there only for your convenience so that you may use the text for the new translations if necessary. You can freely delete any unused messages.

Notes for Developers

Have a look at Notes for Translators. The explanation of using mini-gettext in code follows.

The simple syntax: A string becomes language string by enclosing into _m(" "), e.g.

_m("any string").

It is better to create long strings than to concatenate short ones, because translators may easier understand the meaning.

The parametrized syntax: You must not use variables in language strings. But you can use parameters %1,%2,... with the syntax of

_m("... %1 ... %3 ... %2", array ($param1,$param2,$param3)), e.g.

_m("Click on %1 to get more help.", array ($url)) or
_m("Error %1 in file %2 on line %3", array ($err,$file,$line)).

Always use the array() even when using only one parameter %1.

To update language files, use xmgettext(). Call it by the misc/mgettext/index.php3 script. Have a look on particular settings in the script. You need to provide read-write access for PHP to language files in order to update them. Copy them into another directory (I used ../php_rw/lang, i.e. not a subdir of the AA installation), set permissions, run xmgettext and copy the updated files back. A side remark: If you don't like this overhead, just remember which overhead it took to create and copy all the L_ language constants to new_news_lang.php3 ...

One more thing to take care of is the run-time switching between languages. If you fill in some include file a global variable with translated strings and than change language, it will remain in the old language. You must create a function returning the variable to avoid this.

Hope you will like my mgettext solution,

Jakub

The coding standards are documented in doc/coding.html

We are moving to use phpDoc, the manual for this is at http://phpdoc.org/docs/HTMLframesConverter/default/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html, its pretty comprehensive, and there is a need for a brief version that shows how we use it - any volunteers!

This FAQ interface was developed by Jason at Commons.ca

APC ActionApps is a free software content management system initiated by the Association for Progressive Communications (APC) APC - Internet and ICTs for social justice and development